docs: add MkDocs Material site with versioned GitHub Pages deployment#21
Merged
Conversation
- Add mkdocs-material and mike to dev dependencies - Configure MkDocs Material with navigation tabs, code copy, and Mermaid diagram support via pymdownx.superfences - Add docs/index.md as the site home page (adapted from README) - Add GitHub Actions workflow to deploy versioned docs on release tags via mike, with manual workflow_dispatch for initial deploy Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a MkDocs Material documentation site for the project and adds a GitHub Actions workflow to publish versioned documentation to GitHub Pages using mike, aligning the repo’s existing docs/ content with a navigable docs site.
Changes:
- Add
mkdocs-materialandmiketo the dev dependency group (and updateuv.lockaccordingly). - Add
mkdocs.ymlconfiguring MkDocs Material, navigation, andmikeversioning. - Add a
DocsGitHub Actions workflow to deploy versioned documentation onv*tags (and via manual dispatch).
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
uv.lock |
Locks new dev dependencies required for MkDocs Material + mike. |
pyproject.toml |
Adds mkdocs-material and mike to the dev dependency group. |
mkdocs.yml |
Defines the MkDocs Material site config, nav, and mike plugin settings. |
docs/index.md |
Adds a MkDocs home page adapted from the project README. |
.github/workflows/docs.yml |
Deploys versioned docs to gh-pages on tags / manual trigger. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
pymdownx.superfences only assigns the .mermaid CSS class; the JS bundle must be loaded explicitly for client-side rendering. Add mermaid@11 via unpkg and an init script that re-runs Mermaid on every Material page navigation via document$. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace pip install mkdocs-material mike with astral-sh/setup-uv + uv sync so the docs job uses the pinned uv.lock and matches the CI convention. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add paths filter so any push to main that touches docs/ or mkdocs.yml also publishes the site, not just release tags. Introduce a Resolve version step that picks the right version per trigger: workflow_dispatch input, tag name, or the last released version from semantic_release when triggered by a branch push. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Tag names (v0.4.0) and semantic_release output (0.4.0) were producing inconsistent version directories. Strip the leading v from all sources so every trigger produces the same label format (e.g. 0.4.0). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mkdocs-materialandmikeas dev dependencies (pinned viauv.lock) for local preview and versioned deploymentnavigation.tabs,navigation.top, code copy/annotate, and Mermaid diagram rendering viapymdownx.superfences+extra_javascriptinit scriptdocs/index.mdas the site home page, adapted from the rootREADME.md.github/workflows/docs.ymlthat deploys versioned docs to GitHub Pages viauv run mike deploy, triggered by:v*release tagsmainthat touchesdocs/**ormkdocs.yml(withpathsfilter to avoid spurious deploys)workflow_dispatchvstripped) so tag pushes, branch pushes, and manual deploys all produce the same format (e.g.0.4.0)Test plan
uv sync && uv run mkdocs serveand verify all pages render, including Mermaid diagrams inarchitecture.mdandbest-practices.mdworkflow_dispatchfrom GitHub Actions UI with0.4.0for the initial deploy (requiresgh-pagesbranch to exist and GitHub Pages enabled in repo Settings → Pages → Source: branchgh-pages)maintouching onlysrc/does not trigger the docs workflow🤖 Generated with Claude Code